Crate float_eq

source · [−]
Expand description

Compare IEEE floating point primitives, structs and collections for equality.

This is API reference documentation. For introductory material, guides and discussion see the float_eq guide.

Basic usage

This crate provides boolean comparisons via float_eq! and float_ne!:

use float_eq::float_eq;

if (float_eq!(y_pos, 0.0, abs <= 0.000_1)) {
   //...
}

And asserts via assert_float_eq! and assert_float_ne!:

use float_eq::assert_float_eq;

const TOL: f32 = 0.000_366_210_94;
assert_float_eq!(0.1f32.recip(), 10.0, r2nd <= TOL);

Each of which invokes a specific comparison algorithm with an explictly provided toelrance. In these examples:

  • abs <= 0.000_1 is an absolute tolerance comparison with a tolerance of 0.000_1.
  • r2nd <= TOL is a relative tolerance comparison with a tolerance of TOL, scaled to the precision of the second operand.

Comparison algorithms

These are always of the form CHECK <= tol, where CHECK is one of:

When comparing homogeneous composite types that implement FloatEqAll, variants that use a uniform tol across all fields are also available:

Note: rel and rel_all are legacy aliases for rmax and rmax_all, but using the more precise algorithm names is recommended.

Combining checks

If multiple checks are specified in either a boolean comparison or an assert, they are applied left to right and will shortcut on success. For example:

float_eq!(a, b, abs <= abs_tol, ulps <= ulps_tol)

Is equivalent to:

float_eq!(a, b, abs <= abs_tol) || float_eq!(a, b, ulps <= ulps_tol)

Extending float_eq over custom types

See How to compare custom types.

Macros

assert_float_eq
Asserts that two floating point expressions are equal to each other.
assert_float_ne
Asserts that two floating point expressions are not equal to each other.
debug_assert_float_eq
Asserts that two floating point expressions are equal to each other.
debug_assert_float_ne
Asserts that two floating point expressions are not equal to each other.
float_eq
Checks if two floating point expressions are equal to each other.
float_ne
Checks if two floating point expressions are not equal to each other.

Structs

ComplexUlps
The absolute difference between two floating point num::Complex<T> instances in ULPs.

Traits

AssertFloatEq
Debug context for when an assert fails.
AssertFloatEqAll
Debug context for when an assert using an all check fails.
FloatEq
Compare IEEE floating point values for equality using per-field tolerances.
FloatEqAll
Compare IEEE floating point values for equality using a uniform tolerance.
FloatEqDebugUlpsDiff
Per-field results of ULPs based diff calculations.
FloatEqUlpsTol
Per-field tolerances for ULPs comparisons.

Type Definitions

ComplexUlps32
ComplexUlps<T> type matching num::Complex32.
ComplexUlps64
ComplexUlps<T> type matching num::Complex64.
DebugUlpsDiff
Per-field results of ULPs based diff calculations.
UlpsTol
Per-field tolerances for ULPs comparisons.

Attribute Macros

derive_float_eq
Helper for deriving the various float_eq traits.